<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Histogram datatype | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="mapping-types.html" title="Field datatypes">
<link rel="prev" href="dense-vector.html" title="Dense vector datatype">
<link rel="next" href="flattened.html" title="Flattened datatype">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="mapping.html">Mapping</a></span>
»
<span class="breadcrumb-link"><a href="mapping-types.html">Field datatypes</a></span>
»
<span class="breadcrumb-node">Histogram datatype</span>
</div>
<div class="navheader">
<span class="prev">
<a href="dense-vector.html">« Dense vector datatype</a>
</span>
<span class="next">
<a href="flattened.html">Flattened datatype »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="histogram"></a>Histogram datatype<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/histogram.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>A  field to store pre-aggregated numerical data representing a histogram.
This data is defined using two paired arrays:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
A <code class="literal">values</code> array of <a class="xref" href="number.html" title="Numeric datatypes"><code class="literal">double</code></a> numbers, representing the buckets for
the histogram. These values must be provided in ascending order.
</li>
<li class="listitem">
A corresponding <code class="literal">counts</code> array of <a class="xref" href="number.html" title="Numeric datatypes"><code class="literal">integer</code></a> numbers, representing how
many values fall into each bucket. These numbers must be positive or zero.
</li>
</ul>
</div>
<p>Because the elements in the <code class="literal">values</code> array correspond to the elements in the
same position of the <code class="literal">count</code> array, these two arrays must have the same length.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
A <code class="literal">histogram</code> field can only store a single pair of <code class="literal">values</code> and <code class="literal">count</code> arrays
per document. Nested arrays are not supported.
</li>
<li class="listitem">
<code class="literal">histogram</code> fields do not support sorting.
</li>
</ul>
</div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="histogram-uses"></a>Uses<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/histogram.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">histogram</code> fields are primarily intended for use with aggregations. To make it
more readily accessible for aggregations, <code class="literal">histogram</code> field data is stored as a
binary <a class="xref" href="doc-values.html" title="doc_values">doc values</a> and not indexed. Its size in bytes is at most
<code class="literal">13 * numValues</code>, where <code class="literal">numValues</code> is the length of the provided arrays.</p>
<p>Because the data is not indexed, you only can use <code class="literal">histogram</code> fields for the
following aggregations and queries:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-percentile-aggregation.html" title="Percentiles Aggregation">percentiles</a> aggregation
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-percentile-rank-aggregation.html" title="Percentile Ranks Aggregation">percentile ranks</a> aggregation
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-boxplot-aggregation.html" title="Boxplot Aggregation">boxplot</a> aggregation
</li>
<li class="listitem">
<a class="xref" href="query-dsl-exists-query.html" title="Exists query">exists</a> query
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="mapping-types-histogram-building-histogram"></a>Building a histogram<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/histogram.asciidoc">edit</a>
</h3>
</div></div></div>
<p>When using a histogram as part of an aggregation, the accuracy of the results will depend on how the
histogram was constructed. It is important to consider the percentiles aggregation mode that will be used
to build it. Some possibilities include:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
For the <a class="xref" href="search-aggregations-metrics-percentile-aggregation.html" title="Percentiles Aggregation">T-Digest</a> mode, the <code class="literal">values</code> array represents
the mean centroid positions and the <code class="literal">counts</code> array represents the number of values that are attributed to each
centroid. If the algorithm has already started to approximate the percentiles, this inaccuracy is
carried over in the histogram.
</li>
<li class="listitem">
For the <a class="xref" href="search-aggregations-metrics-percentile-aggregation.html#_hdr_histogram" title="HDR Histogram">High Dynamic Range (HDR)</a> histogram mode, the <code class="literal">values</code> array represents fixed upper
limits of each bucket interval, and the <code class="literal">counts</code> array represents the number of values that are attributed to each
interval. This implementation maintains a fixed worse-case percentage error (specified as a number of significant digits),
therefore the value used when generating the histogram would be the maximum accuracy you can achieve at aggregation time.
</li>
</ul>
</div>
<p>The histogram field is "algorithm agnostic" and does not store data specific to either T-Digest or HDRHistogram. While this
means the field can technically be aggregated with either algorithm, in practice the user should chose one algorithm and
index data in that manner (e.g. centroids for T-Digest or intervals for HDRHistogram) to ensure best accuracy.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="histogram-ex"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/histogram.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following <a class="xref" href="indices-create-index.html" title="Create index API">create index</a> API request creates a new index with two field mappings:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">my_histogram</code>, a <code class="literal">histogram</code> field used to store percentile data
</li>
<li class="listitem">
<code class="literal">my_text</code>, a <code class="literal">keyword</code> field used to store a title for the histogram
</li>
</ul>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index
{
  "mappings": {
    "properties": {
      "my_histogram": {
        "type" : "histogram"
      },
      "my_text" : {
        "type" : "keyword"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/627.console"></div>
<p>The following <a class="xref" href="docs-index_.html" title="Index API">index</a> API requests store pre-aggregated for
two histograms: <code class="literal">histogram_1</code> and <code class="literal">histogram_2</code>.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index/_doc/1
{
  "my_text" : "histogram_1",
  "my_histogram" : {
      "values" : [0.1, 0.2, 0.3, 0.4, 0.5], <a id="CO295-1"></a><i class="conum" data-value="1"></i>
      "counts" : [3, 7, 23, 12, 6] <a id="CO295-2"></a><i class="conum" data-value="2"></i>
   }
}

PUT my_index/_doc/2
{
  "my_text" : "histogram_2",
  "my_histogram" : {
      "values" : [0.1, 0.25, 0.35, 0.4, 0.45, 0.5], <a id="CO295-3"></a><i class="conum" data-value="1"></i>
      "counts" : [8, 17, 8, 7, 6, 2] <a id="CO295-4"></a><i class="conum" data-value="2"></i>
   }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/628.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO295-1"><i class="conum" data-value="1"></i></a><a href="#CO295-3"></a></p>
</td>
<td align="left" valign="top">
<p>Values for each bucket. Values in the array are treated as doubles and must be given in
increasing order. For <a class="xref" href="search-aggregations-metrics-percentile-aggregation.html#search-aggregations-metrics-percentile-aggregation-approximation" title="Percentiles are (usually) approximate">T-Digest</a>
histograms this value represents the mean value. In case of HDR histograms this represents the value iterated to.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO295-2"><i class="conum" data-value="2"></i></a><a href="#CO295-4"></a></p>
</td>
<td align="left" valign="top">
<p>Count for each bucket. Values in the arrays are treated as integers and must be positive or zero.
Negative values will be rejected. The relation between a bucket and a count is given by the position in the array.</p>
</td>
</tr>
</table>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="dense-vector.html">« Dense vector datatype</a>
</span>
<span class="next">
<a href="flattened.html">Flattened datatype »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
